home *** CD-ROM | disk | FTP | other *** search
/ 400 MB of Top PC Shareware / 400 MB Of Top PC Shareware.iso / misc / help30.exe / 9368.TXT next >
Text File  |  1992-06-19  |  26KB  |  424 lines
  1. TITLE:   Using Ami Pro 2.0 to Create Windows 3.X Help Files
  2. PRODUCT: Ami Pro 2.0
  3. DATE:    17-Jun-1992
  4.  
  5. PROBLEM: 
  6.  
  7. How can documents used to generate Windows 3.X help files be created in Ami 
  8. Pro?
  9.  
  10. SOLUTION: 
  11.  
  12. NOTE: This Technical Support Note provides information on how to use certain 
  13. Ami Pro functions to create documents that can be compiled into Windows 3.X 
  14. help files.  It does not provide instructions on how to structure a help file, 
  15. how to compile a help file, or explain help file terminology.  Please refer to 
  16. your Windows help compiler manual for complete information on creating help 
  17. files.  Have a thorough understanding of creating Windows help files before 
  18. using the information in this Note.
  19.  
  20. Documents used to create Windows 3.X help files can be created in Ami Pro and 
  21. exported to a Rich Text Format file.  The rich text file is then compiled into 
  22. a Windows help file using a Windows help compiler.  Style sheets (HELPATM.STY 
  23. is configured for use with Adobe Type Manager that is supplied with Ami Pro 
  24. 2.0 and HELPTT.STY is configured for use with Windows 3.1 TrueType fonts) and 
  25. several macros that automate footnote creation and other tasks are available 
  26. from Lotus.  The style sheets have paragraph styles created with the 
  27. appropriate superscript characters for the footnotes that are used in creating 
  28. Windows help file text.  Other paragraph styles are included which can be used 
  29. for indented paragraphs, numbered lists, bulleted lists, etc.
  30.  
  31. The style sheets and macros can be obtained on a disk by mail from the Lotus 
  32. Word Processing Division Customer Service Department, 404-399-5505.  The files 
  33. can be obtained electronically from library 2 Lotus Write and Ami Pro files on 
  34. the LotusWP CompuServe forum or the Lotus WPD bulletin board, 404-395-7707.  
  35. Download the file HELP20.EXE from the bulletin board or from CompuServe.
  36.  
  37. HOW TO COPY THE STYLE SHEET FILES AND THE MACRO FILES
  38.  
  39.   1. Access a DOS prompt.
  40.   2. Insert the floppy disk containing the help style sheets and macro files 
  41.      into a floppy drive.
  42.   3. Access the drive containing the disk by typing the drive letter followed 
  43.      by a colon.  For example, if the disk is in drive A, type at the DOS 
  44.      prompt:
  45.      A: and press ENTER.
  46.   4. At the DOS prompt type:
  47.      COPY *.STY X:\PATHNAME\STYLES and press ENTER (X:\PATHNAME\STYLES should 
  48.      be the correct path to the directory where Ami Pro style sheets are 
  49.      stored.  This is usually C:\AMIPRO\STYLES).
  50.   5. At the DOS prompt type:
  51.      COPY *.SMM X:\PATHNAME\MACROS and press ENTER (X:\PATHNAME\MACROS should 
  52.      be the correct path to the directory where Ami Pro macro files are 
  53.      stored.  This is usually C:\AMIPRO\MACROS).
  54.  
  55. HOW TO CREATE HELP FILE TEXT IN AMI PRO
  56.  
  57. To use one of the Ami Pro help style sheets to format text for use in creating 
  58. Windows help files, follow the steps below.  Note:  The style sheet 
  59. HELPATM.STY has the font for each paragraph style set to the Adobe Type 
  60. Manager font Arial MT.  Use this style sheet if you use Adobe Type Manager.  
  61. The style sheet HELPTT.STY has the font for each paragraph style set to the 
  62. Windows 3.1 TrueType font Arial.  Use this style sheet if you use TrueType 
  63. fonts.
  64.  
  65. Keep in mind the following guidelines while creating help files in Ami Pro:
  66.  
  67.   1. Each help topic should be on a separate page.  If a help topic ends 
  68.      before a full page, the last paragraph of the topic should end with a 
  69.      hard return (press ENTER).  This will ensure that RTF paragraph styles 
  70.      will not span page breaks.  Insert a page break after the last paragraph 
  71.      (choose Page / Breaks / Insert page break).  
  72.   2. Do not use the Text menu to assign capitalization to text.
  73.   3. If you include numbered procedural steps, apply the Numbered List 
  74.      paragraph style and use the macro HLPNUMBR.SMM (choose Tools / Macros / 
  75.      Playback).  This macro inserts a number at the beginning of all 
  76.      paragraphs that use the Numbered List paragraph style.  The macro 
  77.      restarts numbering with 1 after encountering a paragraph using the 
  78.      Heading 2 paragraph style.
  79.   4. If you include bulleted lists, apply the Bulleted List paragraph style 
  80.      and use the macro HLPBULET.SMM.  This macro inserts a bullet at the 
  81.      beginning of all paragraphs that use the Bulleted List paragraph style.  
  82.      
  83.      Note:  Do not use a style with Ami Pro special effects for numbered or 
  84.      bulleted paragraphs.  The special effects numbers and bullets in 
  85.      paragraph styles do not export to Rich Text Format that the Windows help 
  86.      compiler uses.  
  87.   5. If you use the terms Mouse and Keyboard to give separate instructions for 
  88.      mouse and keyboard commands, the macros HLPMOUSE.SMM and HLPKEYBD.SMM can 
  89.      be used to insert the words Mouse: or Keyboard: at the beginning of a 
  90.      paragraph.
  91.   6. Use normal apostrophe and quote marks instead of typographic characters 
  92.      for those marks.
  93.   7. Only alphabetic and numeric characters and underlines are recognized as 
  94.      footnote text by the Microsoft Windows Help Compiler.
  95.   8. Ami Pro's protected text is the equivalent of Microsoft Word's hidden 
  96.      text.  Protected text in Ami Pro translates to hidden text when exported 
  97.      to Rich Text Format.
  98.  
  99.   How to use a help style sheet
  100.  
  101.   The Ami Pro help style sheets provide the following styles:
  102.  
  103.   Context              Use for Context footnotes.  The macro HLPCNTXT.SMM 
  104.                        automatically applies this style to a Context 
  105.                        footnote.
  106.  
  107.   Title                Use for Title footnotes.  The macro HLPTITLE.SMM 
  108.                        automatically applies this style to a Title footnote.
  109.  
  110.   KeyWord              Use for KeyWord footnotes.  The macro HLPKYWD.SMM 
  111.                        automatically applies this style to a KeyWord 
  112.                        footnote.
  113.  
  114.   Browse               Use for Browse footnotes.  The macro HLPBRWSE.SMM 
  115.                        automatically applies this style to a Browse footnote.
  116.  
  117.   Body Text            Use for topic descriptions and other general text.  
  118.                        This style is hyphenated, has .05 paragraph spacing 
  119.                        below, and will break within pages and columns.
  120.  
  121.   Heading 1            Use for help topic context string.  This style is not 
  122.                        hyphenated, contains additional .05 paragraph spacing 
  123.                        above and below, and will keep with the next 
  124.                        paragraph.
  125.  
  126.   Heading 2            Use for help topic titles.  This style is not 
  127.                        hyphenated, contains additional .05 spacing above and 
  128.                        below, and will break within pages and columns.
  129.  
  130.   Numbered List        Use for numbered lists.  This style left aligns the 
  131.                        first line and indents remaining lines of a paragraph. 
  132.                        The style does not have any special effects.  The 
  133.                        number is applied by using the macro HLPNUMBR.SMM.  
  134.                        HLPNUMBR.SMM inserts a tab after a number and a period 
  135.                        so that the first line of text will align on a style 
  136.                        tab at the same position as the remaining lines of the 
  137.                        paragraph.  The style is hyphenated, has additional .05 
  138.                        paragraph spacing below, and will break within pages 
  139.                        and columns.
  140.  
  141.   Bulleted List        Use for bulleted lists.  This style left aligns the 
  142.                        first line and indents remaining lines of a paragraph. 
  143.                        The style does not have any special effects.  The 
  144.                        bullet is applied by using the macro HLPBULET.SMM.  
  145.                        HLPBULET.SMM inserts a tab after a bullet character so 
  146.                        that the first line of text will align on a style tab 
  147.                        at the same position as the remaining lines of the 
  148.                        paragraph.  The style is hyphenated, has additional .05 
  149.                        paragraph spacing below, and will break within pages 
  150.                        and columns.
  151.  
  152.   CrossRef             Use for cross-references or other paragraphs that are 
  153.                        indented and do not need additional paragraph spacing. 
  154.                        This style is not hyphenated, has no additional 
  155.                        paragraph spacing above or below, and will break within 
  156.                        pages and columns.
  157.  
  158.   Term                 This style utilizes a bold font.  You may want to use 
  159.                        it for bolded terms.  The style is not hyphenated or 
  160.                        indented, has no additional paragraph spacing above or 
  161.                        below, and will break within a page or column.
  162.  
  163.   Note                 This style utilizes an indention for all lines.  Use it 
  164.                        for cross-references or other paragraphs that are 
  165.                        indented and need additional paragraph spacing.  This 
  166.                        style is not hyphenated, has .05 additional paragraph 
  167.                        spacing below, and will break within pages or columns.
  168.  
  169.    1.  Choose File / New.
  170.    2.  Select either the style sheet HELPATM.STY or HELPTT.STY from the "Style 
  171.        sheet for new document" list box.
  172.    3.  Choose OK.
  173.    4.  Type help text and create the necessary footnotes.  If you want to use 
  174.        the help macros from Lotus to assist you in constructing the document, 
  175.        follow the section titled "How to use the help macros".  If you want to 
  176.        manually create the footnotes, cross-references, and help text, follow 
  177.        the section titled "How to manually enter footnotes and cross-
  178.        references".  After the document is completed, continue with step 5 
  179.        below.
  180.    5.  Save the file by choosing File / Save.
  181.    6.  Specify a name for the Ami Pro file in the "File name" edit box.  Do 
  182.        not place an X in either of the check boxes for "Keep format with 
  183.        document" or "Ami Pro 1.2 format".  This will ensure that the file will 
  184.        reference the help style sheet and any changes that may be made to the 
  185.        style sheet.
  186.    7.  Choose OK.  The text is now saved in an Ami Pro file that can be edited 
  187.        at a later time.
  188.    8.  With the Ami Pro file opened, choose File / Save As.
  189.    9.  Choose Rich Text Format in the "File type" list box.
  190.   10.  Specify the desired name for the rich text file in the "File name" edit 
  191.        box.
  192.   11.  Choose OK.
  193.   12.  The rich text file is ready for compiling with the Windows help 
  194.        compiler.
  195.  
  196.   How to use the help macros
  197.  
  198.   The help macros assist you in creating context, title, keyword, and browse 
  199.   footnotes, create cross-references and definitions, and create various text 
  200.   items.  The macro names and functions are as follows:
  201.    HLPCNTXT.SMM        Creates a Context footnote
  202.    HLPTITLE.SMM        Creates a Title footnote
  203.    HLPKYWD.SMM         Creates a KeyWord footnote
  204.    HLPBRWSE.SMM        Creates a Browse footnote
  205.    HLPDEF.SMM          Creates a definition
  206.    HLPXREF.SMM         Creates a cross-reference
  207.    HLPBULET.SMM        Inserts a bullet and a tab at the beginning of all 
  208.                        bulleted list paragraphs.
  209.    HLPNUMBR.SMM        Inserts a number, a period, and a tab at the beginning 
  210.                        of all Numbered List paragraphs.  Sequential numbering 
  211.                        starts over with number 1 when the macro encounters a 
  212.                        paragraph using the Heading 2 paragraph style.
  213.    HLPKEYBD.SMM        Inserts the word Keyboard: at the beginning of the 
  214.                        current paragraph and bolds the word.
  215.    HLPMOUSE.SMM        Inserts the word Mouse: at the beginning of the current 
  216.                        paragraph and bolds the word.
  217.  
  218.  Keep in mind the following guidelines while using the Ami Pro help macros:
  219.  
  220.   1. The help macros assume that the first line of the page contains only a 
  221.      return, and the title for the help topic is on the second line.  You must 
  222.      modify the macros if you do not use this format.
  223.   2. If you will be using several types of footnotes, create them in this 
  224.      order: Context, Title, KeyWord, and Browse.  Each help macro places a 
  225.      footnote reference identifier (#,$,+,K) at the location of the insertion 
  226.      point, and creates the desired footnote at the bottom of the page.  
  227.  
  228.  To use the Ami Pro help macros in conjunction with the help style sheets, 
  229.  follow the procedure below:
  230.  
  231.   1. Using either the HELPATM.STY or the HELPTT.STY style sheet, place the 
  232.      insertion point on line 1 of the page and apply the style Body Text.  
  233.      Press ENTER.  This inserts a blank line which will be used to hold the 
  234.      footnote references.
  235.   2. On line 2 of the page apply the paragraph style Heading 1.  Type the 
  236.      unique internal name for the help topic (context string) and press 
  237.      ENTER.
  238.   3. On line 3 of the page apply the paragraph style Heading 2.  Type the 
  239.      title of a help topic and press ENTER.  This help topic title displays 
  240.      when a user creates bookmarks and performs searches in help.
  241.   4. On line 4 apply the paragraph style Body Text.  Type the paragraph of 
  242.      description for the help topic specified in step 3.  Press ENTER after 
  243.      you have completed the paragraph.
  244.   5. Continue using Heading 2 and Body Text styles for subsequent help topic 
  245.      titles and descriptions.
  246.   6. Place the insertion point on the first line of the page.
  247.   7. Choose Tools / Macros / Playback.  Note: The macro HLPCNTXT.SMM, which 
  248.      you will use, assumes that the insertion point is on line one of the page 
  249.      and the internal title (context string) for the help topic is on the 
  250.      second line.  You will need to modify the macro if you do not use this 
  251.      format.  
  252.   8. Specify the name HLPCNTXT.SMM in the "Macros" list box.  
  253.   9. Choose OK.  The macro creates a Context footnote using the context string 
  254.      on line 2.  It copies the context string, creates a Context footnote, and 
  255.      pastes the context string in that footnote.  It then capitalizes the 
  256.      footnote text, converts any spaces to underlines, and places the 
  257.      insertion point on the first line of the page after the # identifier for 
  258.      the Context footnote.
  259.  10. With the insertion point still on line one immediately after the # 
  260.      identifier, choose Tools / Macros / Playback.  Note: The macro 
  261.      HLPTITLE.SMM, which you will use, assumes that the Context footnote has 
  262.      already been created, and that the insertion point is immediately after 
  263.      the Context footnote identifier (#) on the first line of the page.  You 
  264.      will need to modify the macro if you do not use this format.
  265.  11. Specify the name HLPTITLE.SMM in the "Macros" list box.
  266.  12. Choose OK.  The macro creates a Title footnote from the title for a help 
  267.      topic.  It copies the title for the topic, creates a Title footnote, and 
  268.      pastes the title in that footnote.  It then places the insertion point on 
  269.      the first line of the page after the $ identifier for the Title 
  270.      footnote.
  271.  13. If you want to create optional keyword footnotes (Windows Help matches 
  272.      the user-entered word in a search to words entered as key words in the 
  273.      help topic), do so only if the help topic has a Title footnote.  The 
  274.      title of the topic appears in the search dialog box when the user 
  275.      searches for the keyword.  Multiple help topics can use the same keyword. 
  276.      The format is keyword;keyword.  For example, windows;commands;dialog 
  277.      boxes
  278.      a. With the insertion point on line one immediately after the $ 
  279.         identifier for the Title footnote, choose Tools / Macros / Playback.  
  280.         Note:  The macro HLPKYWD.SMM, which you will use, assumes that the 
  281.         Context and Title footnotes have already been created and that the 
  282.         insertion point is immediately after the Title footnote identifier ($) 
  283.         on the first line of the page.  You will need to to modify the macro 
  284.         if you do not use this format. 
  285.      b. Choose the name HLPKYWD.SMM from the "Macros" list box.  
  286.      c. Choose OK.
  287.      d. Type the keyword entries for the footnote.  Press ESC after you have 
  288.         typed the last keyword entry.  This places the insertion point at the 
  289.         end of line one.
  290.  14. If you use a browse sequence, enter the browse footnote last.  The format 
  291.      is topic:nnn where topic is the sequence list name and nnn is the 
  292.      sequence number for the topic.  For example, BASICS:010.  The numbers 
  293.      should all have the same length.  For single numbers, use two zeroes as 
  294.      place holders for the first two digits (001, for example), for two-digit 
  295.      numbers, use one zero as a place holder (010, for example).  
  296.      If browse sequences are numbered in increments of five or ten and use one 
  297.      or more zeroes as place holders, you can easily insert additional topics 
  298.      at a later time.  Tip: If your help files contain many help topics, 
  299.      produce a table of contents to obtain a list of all the topics.  This can 
  300.      be done by creating a table in a separate Ami Pro file (choose Tools / 
  301.      Tables).  The table should contain a row for each help topic.  Create a 
  302.      formula (choose Table / Edit formula) in column A of the table to 
  303.      sequentially number the topics.  For example, cell A1 could have the 
  304.      value 5.  Create the formula A1+5 in cell A2.  Copy the formula in A2 to 
  305.      the remainder of the cells in column A to get sequential numbering in 
  306.      five-unit increments.  Type the help topic titles in column B.  Use the 
  307.      table as a reference when you assign the Browse sequence numbers to help 
  308.      topics, adding the appropriate number of zeroes as place holders.
  309.  15. Follow these steps if you want to create a cross-reference (jump term):  
  310.      Note:  If the text you type matches the text in a Context footnote for a 
  311.      help topic, you can run the HLPXREF.SMM macro.  If the text you type does 
  312.      not match a Context footnote, you will need to manually create the cross-
  313.      reference following the procedure in the section titled "How to manually 
  314.      enter footnotes and cross-references".
  315.      a. Place the insertion point where you want to create a cross-reference.
  316.      b. Type the text you want the user to see as the cross-reference.  This 
  317.         is usually the title for a help topic.
  318.      c. Select (shade) the cross-reference text.  Note:  The text must be 
  319.         selected in order for the macro to play back properly.  The selected 
  320.         text must match the text in a Context footnote for a help topic.  Do 
  321.         not double-click on a single word to select it because this selects 
  322.         both the word and the space after the word.
  323.      d. Choose Tools / Macros / Playback.
  324.      e. Select the name HLPXREF.SMM in the "Macros" list box.
  325.      f. Choose OK.  HLPXREF.SMM creates a cross-reference from the selected 
  326.         text.  It copies the selected text and pastes the text immediately 
  327.         after the original text.  It then capitalizes the cross-reference 
  328.         text, converts any spaces to underlines, protects the text, double 
  329.         underlines the original text, and places the insertion point at the 
  330.         end of the line.
  331.  16. Follow these steps if you want to create a definition term.
  332.      a. Place the insertion point where you want to create a term that 
  333.         requires definition.
  334.      b. Type the term.  This is usually the title for a help topic.  
  335.      c. Select (shade) the term.  Note:  The text must be selected in order 
  336.         for the macro to play back properly.  The selected text must match the 
  337.         text in a Context footnote for a help topic.  Do not double-click on a 
  338.         single word to select it because this selects both the word and the 
  339.         space after the word.
  340.      d. Choose Tools / Macros / Playback.
  341.      e. Select the name HLPDEF.SMM in the "Macros" list box.
  342.      f. Choose OK.  HLPDEF.SMM creates a definition term from the selected 
  343.         text.  It copies the selected text and pastes the text immediately 
  344.         after the original text.  It then capitalizes the definition term 
  345.         text, converts any spaces to underlines, protects the text, underlines 
  346.         the original text, and places the insertion point at the end of the 
  347.         line.
  348.  17. Follow these steps if you want to use the HLPMOUSE.SMM or HLPKEYBD.SMM 
  349.      macros.
  350.      a. Place the insertion point in the paragraph that should be preceded by 
  351.         the word Mouse: or Keyboard:.
  352.      b. Choose Tools / Macros / Playback.
  353.      c. Choose the name HLPMOUSE.SMM (to insert the word Mouse:) or the name 
  354.         HLPKEYBD.SMM (to insert the word Keyboard:) in the "Macros" list box.
  355.      d. Choose OK.  The bolded word Mouse: or Keyboard: is inserted at the 
  356.         beginning of the paragraph.
  357.  18. Follow these steps if you want to use the HLPNUMBR.SMM macro.
  358.      a. Assign the paragraph style Numbered List to all paragraphs that you 
  359.         want numbered.  Assign a paragraph style by pressing the function key 
  360.         assigned to the paragraph style, selecting a paragraph style name from 
  361.         the paragraph styles list box, or selecting a style from the style 
  362.         status button on the status bar while the insertion point is in the 
  363.         paragraph.
  364.      b. Choose Tools / Macros / Playback.
  365.      c. Select the name HLPNUMBR.SMM from the "Macros" list box.
  366.      d. Choose OK.  The macro searches for the style Numbered List throughout 
  367.         the file.  Each time a paragraph using that style is located, a 
  368.         number, period, and tab are inserted at the beginning of the 
  369.         paragraph.  The numbers are sequential until a paragraph using the 
  370.         Heading 2 style is encountered.  The first paragraph using the 
  371.         Numbered List style after a paragraph using the Heading 2 style is 
  372.         numbered one.  Numbers continue sequentially until the next Heading 2 
  373.         style is encountered, then the numbering starts again with 1.  The 
  374.         macro assumes that each time Heading 2 is used, a new topic has been 
  375.         introduced and numbered list items should start over with number 1 for 
  376.         the new topic.
  377.  19. Follow these steps if you want to use the HLPBULET.SMM macro.
  378.      a. Assign the paragraph style Bulleted List to all paragraphs that you 
  379.         want bulleted.  Assign a paragraph style by pressing the function key 
  380.         assigned to the paragraph style, selecting a paragraph style name from 
  381.         the paragraph styles list box, or selecting a style from the style 
  382.         status button on the status bar while the insertion point is in the 
  383.         paragraph.
  384.      b. Choose Tools / Macros / Playback.
  385.      c. Select the name HLPBULET.SMM from the "Macros" list box.
  386.      d. Choose OK.  The macro searches for the style Bulleted List throughout 
  387.         the file.  Each time a paragraph using that style is located, a bullet 
  388.         from the Windows Symbol font and a tab are inserted at the beginning 
  389.         of the paragraph.
  390.  
  391.  How to manually enter footnotes and cross-references
  392.  
  393.   1. Creating footnotes
  394.      a. Using either the HELPATM.STY or the HELPTT.STY style sheet, place the 
  395.         insertion point where a footnote reference identifier should appear.
  396.      b. Choose Tools / Footnote / Insert Footnote.
  397.      c. Choose OK.
  398.      d. The insertion point will be placed near the bottom of the page.
  399.      e. Type the desired footnote text.  Note:  If you are typing a Context 
  400.         footnote, you must convert any spaces between words in the Context 
  401.         footnote to underlines, and capitalize all text in the footnote.  For 
  402.         example, PRINTING_A_DOCUMENT.
  403.      f. Assign the appropriate paragraph style for the help topic.  For 
  404.         example, if a browse sequence is being typed, choose the BROWSE 
  405.         paragraph style.  Assign a paragraph style by pressing the function 
  406.         key assigned to the paragraph style, selecting a paragraph style name 
  407.         from the paragraph styles list box, or selecting a style from the 
  408.         style status button on the status bar while the insertion point is in 
  409.         the footnote text.
  410.      g. After typing the footnote text, press ESCAPE to position the insertion 
  411.         point immediately after the footnote reference identifier.
  412.      h. Repeat steps a - g until all footnotes are completed.  
  413.   2. Creating cross-references
  414.      a. Create cross-references by double underlining the text representing 
  415.         the cross-reference and marking the corresponding context string as 
  416.         protected text (select the text, choose Edit / Mark Text / Protected 
  417.         Text).  Create definition terms by single underlining the text 
  418.         representing the definition term and marking the corresponding context 
  419.         string as protected text (select the text, choose Edit / Mark Text / 
  420.         Protected Text).  Note:  Ami Pro's Protected Text is the equivalent of 
  421.         Microsoft Word's Hidden Text.  Protected Text in Ami Pro translates to 
  422.         Hidden Text when exported to Rich Text Format.
  423.  
  424.